docs: rewrite first-person voice to comply with second-person style guide#585
Merged
Conversation
…ages
Per the marketing content guidelines, docs should be written in second
person. Rewrites the three largest offenders (230 of 487 total
first-person pronoun instances):
- system/security.mdx (139 instances): a security/policy page, almost
entirely first-person statements about what Shorebird as a company
does ("we use Google Cloud", "we do not sell your data"). These
can't become "you" statements without changing the facts, so they're
rephrased to third person ("Shorebird uses...") or passive voice
instead.
- code-push/system-architecture.mdx (48 instances): similar pattern -
describes Shorebird's own internal architecture and fork history
("we forked Flutter", "our database"), rephrased the same way.
- code-push/faq.mdx (43 instances): a mix of company statements
(rephrased to third person/passive) and instructional recommendations
("we recommend X" -> "X is recommended" or dropped the pronoun
entirely where the sentence reads fine without it).
Left headings untouched even where they contain "we" (e.g. "What
can't we use Shorebird Code Push for?") since Shorebird.SecondPerson
is scoped to paragraphs only, not headings - these were never flagged
and don't need to change.
This is a partial pass; the remaining ~40 files with first-person
instances will follow in subsequent commits.
…Flutter SDK guides
…ols, fastlane, symbols, release, rollback, update-strategies, architecture-trees, and flutter-version guides
… and getting-started pages
AbhishekDoshi26
approved these changes
Jul 3, 2026
dawn-ducky
reviewed
Jul 6, 2026
Per review feedback, 'we never know anything about your users' reads as a stronger, more direct privacy commitment than the passive third-person phrasing.
…ocs into docs/second-person-voice
tomarra
added a commit
that referenced
this pull request
Jul 6, 2026
Now that PR #585 rewrote all real first-person prose, the only remaining SecondPerson matches are permanent false positives (i.e., a URL slug, 'US' as a country, the default org name, a quoted heading, and one deliberate first-person privacy pledge). Mask those via TokenIgnores and promote the rule to error severity so it actually blocks CI going forward, matching Shorebird.Headings and Shorebird.Exclamation. Vale.Terms stays at warning severity - its code-fence/URL exclusion bug is unrelated and still unresolved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Shorebird.SecondPersonstyle guideline.Shorebird.SecondPersononly scopes to paragraph text.A handful of
Shorebird.SecondPersonmatches remain and are intentional false positives from the pattern-matching rule, not first-person prose:security.mdx— URL slug#can-i-use-shorebird-in-my-countrysystem-architecture.mdx— "US" (United States), matched as the pronoun "us"faq.mdx— link text[How We Bill]quoting an actual page headinghybrid-apps/ios.mdx,hybrid-apps/android.mdx,release.mdx,security.mdx— "i.e." matched as the pronoun "i"account/orgs.mdx— the literal default org name "My Organization"Test plan
npm run buildsucceeds with no broken linksvale(with the not-yet-merged tooling from docs: add style checks for headings and content guidelines #576) shows 0 realShorebird.SecondPersonfindings acrosssrc/content/docs(only the documented false positives above remain)prettier --checkandcspellpass on every changed file